HandStack API 사용하기

전달하려는 주요 내용

• transact 모듈의 업무 계약(Contract)에 따라 클라이언트의 요청을 처리하는 방법을 알아봅니다.

• 데이터 요청을 검증하고, 중계하여 정확한 응답을 전달하도록 설정하는 과정을 실습합니다.

• HandStack이 어떻게 개발 생산성을 높이는지 직접 확인합니다.

transact 모듈이란?

HandStack에서 비즈니스 로직의 핵심 관문 역할을 하는 모듈입니다.

• API 자동 관리

  • 업무 계약(Contract) JSON 파일을 생성하거나 변경하면, 해당 계약을 위한 HTTP POST 엔드포인트를 자동으로 생성하고 관리합니다.

• 주요 기능

  • 요청 데이터 검증 (Validation)
  • 실행 허가 (Authorization)
  • 응답 정보 캐싱 (Caching)
  • 실행 상태 모니터링 (Monitoring)
  • 실행 과정 로깅 (Logging)
  • dbclient, function 등 다른 모듈로 이벤트 라우팅

거래 데이터 흐름

모든 거래 요청은 단 하나의 Endpoint로 수신합니다.

계약(Contract) 문서 살펴보기

transact 모듈은 모든 것을 이 계약 문서에 기반하여 처리합니다.

{
    "ApplicationID": "HDS",
    "ProjectID": "TST",
    "TransactionID": "TST010",
    "Services": [
        {
            "ServiceID": "LD01",
            "Authorize": false,
            "Roles": [ "Administrator", "Master" ],
            "Policys": { "ApplicationRoleID": [ "Bot" ] },
            "ReturnType": "Json",
            "CommandType": "D",
            "SequentialOptions": [...],
            "AccessScreenID": [ "TST010" ],
            "TransactionScope": false,
            "Inputs": [ { "ModelID": "Dynamic", "Type": "Row", ... } ],
            "Outputs": [ { "ModelID": "Dynamic", "Type": "Grid" } ]
        }
    ]
}

계약(Contract) 문서 해부하기 (1/2)

• ApplicationID, ProjectID, TransactionID
  • HDS 앱의 TST 프로젝트에 속한 TST010 거래를 의미합니다.
• ServiceID: TST010 거래 내에서 LD01이라는 서비스 ID로 요청을 식별합니다.
• Authorize: 별도의 인증 절차 없이 누구나 호출할 수 있는 공개된 서비스입니다.
• CommandType: D, F
  • D: 데이터베이스 관련 명령을 수행합니다.
  • F: 함수 관련 명령을 수행합니다.

계약(Contract) 문서 해부하기 (2/2)

• Roles: 인증 토큰에서 프로그램 역할(보안 레벨)에 해당되는 지 확인합니다.
• Policys: 인증 토큰에서 업무 정책(실행 권한)에 포함되는 지 확인합니다.
• AccessScreenID: 특정 화면 ID에서만 접근을 허용합니다.
• SequentialOptions: 여러 거래를 순차적으로 한번에 수행합니다.
• Inputs: 여러 요청을 처리하는 정보를 포함하는 배열입니다.
• Outputs: 여러 응답을 처리하는 정보를 포함하는 배열입니다.

설계 사상: 책임의 분리

transact 모듈은 역할과 책임(R&R)이 분리된 구조를 지향합니다.

• 화면 개발

  • 계약에 정의된 API 명세에 따라 입/출력 데이터만 처리

• 운영 담당

  • 계약의 실행 권한, 로깅, 모니터링 등 시스템 운영에 집중

• 업무 개발

  • 계약에 연결될 실제 비즈니스 로직(DB 쿼리, Function 등) 개발에 집중

더 알아보기: 계약 중심 거래

핸즈온: 계약 목록 조회하고 정보 확인하기

transact 모듈의 module.json 의 다음 보안 항목에 해당하는 클라이언트만 가능

• AuthorizationKey: 기본값 (SystemID + RunningEnvironment + HostName == HANDSTACKDHOSTNAME)
• AllowClientIP: *

# `transact` 모듈이 관리하는 계약 목록 정보를 조회하는 기본 API입니다.
http://localhost:8421/transact/api/transaction/meta

# 특정 계약 상세 정보를 조회하는 기본 API입니다.
http://localhost:8421/transact/api/transaction/retrieve?applicationID=HDS&projectID=TST&transactionID=TST010

핸즈온: 데이터 연동 실습

이제 직접 화면과 서버의 데이터 연동 과정을 체험해 봅시다.

• 1단계: 페이지 자바스크립트 파일에 거래(transaction) 함수 정의하기
• 2단계: HTML 요소에 syn-datafield 속성으로 데이터 Key 연결하기
• 3단계: 조회 버튼에 onclick 이벤트를 연결하여 거래 함수 호출하기
• 4단계: beforeTransaction Hook으로 조회 전 조건을, afterTransaction Hook으로 조회 후 결과를 확인하기
• 5단계: 브라우저에서 버튼을 클릭하고 개발자 도구(F12) 네트워크 탭에서 실제 통신 데이터 확인하기

결과 확인 및 장점

계약 파일 하나 만들었을 뿐인데,
HandStack이 알아서 복잡한 API 엔드포인트를
자동으로 만들어 줬어요!

백엔드 개발 시간이 획기적으로 줄어듭니다.

• 이제 우리는 http://localhost:8421/transact/api/transaction/execute 주소로 TST010 거래를 요청할 수 있는 준비가 완료되었습니다.